<html>
<!-- $LastChangedDate: 2009-11-22 22:39:11 -0500 (Sun, 22 Nov 2009) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - Base Module</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - Base Module</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Sharing Objects'>Sharing Objects</a></li>  <!-- objects in general sense -->
      <ul>
        <li><a href='#Shared and SharedPtr'>Shared and SharedPtr</a></li>
        <li><a href='#UniquePtr'>UniquePtr</a></li>
      </ul>
  <li><a href='#Timer'>Timer</a></li>
      <ul>
        <li><a href='#Pausing Program'>Pausing Program</a></li>
      </ul>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Sharing Objects'></a>  <!-- objects in the general sense -->
<h2>Sharing Objects</h2>
<p><!--date-->[2006,2007/06]</p>
<p>
<font size='+2' color='darkred'>
<i>[2008/02] shptr is a #define for osg::ref_ptr which is equivalent.</i>
<br><i>This is a vestige from Version 2 (SharedPtr code isn't compiled in Version 3).</i>
</font>
</p>
<p>
C++ objects can be shared in different ways (objects in the general sense).
</p>
<a name='Shared and SharedPtr'></a>
<a name='Shared'></a>
<a name='SharedPtr'></a>
<h3>Shared and SharedPtr</h3>
<p>
SharedPtr is a smart pointer that maintains a reference-count.
A requirement is that objects to share must be derived from Shared.
Shared provides storage for the reference-count,
intrusively in an object itself, since Shared is its base class.
</p>
<p>
Besides sharing, SharedPtr simplifies object ownership.
SharedPtr auto-deletes the object when it is no longer referenced,
eliminating needing to explicitly delete an object.
</p>
<p>
<b>NOTE:</b> For speed, regular SharedPtr does not support NULL.
The slower variant SharedPtrNull does.
</p>
<p>
A particular Shared object is interchangable with different kinds of SharedPtrs.
SharedPtr::PTR() can extract the Shared object which can be used
to create another SharedPtr variable of the same or different type.
</p>
<p>
An idiom is using a SharedPtr for its auto-deletion ability,
even though the object really isn't shared.
</p>
<a name='UniquePtr'></a>
<h3>UniquePtr</h3>
<p>
Constructors with the potential to produce multitudes of objects
with duplicate values can be constrained using UniquePtr.
When given an object, the UniquePtr ctor may substitute the object
with a shared one in a private STL set and delete the given duplicate object.
UniquePtr shares copies that it owns rather than originals (which it doesn't own).
</p>


<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Timer'></a>
<h2>Timer</h2>
<p><!--date-->[2008/12]</p>
<p>
The Timer singleton has to be driven by an external tick.
Timer is a registry for callbacks.
Timer can be <i>partially</i> disabled by Timer::Enable(false).
While disabled, most callbacks won't be called, but Timer will still track time.
Special callbacks (keyboard handlers) that need to be called always
can prevent themselves being disabled.
</p>
<a name='Pausing Program'></a>
<h3>Pausing Program</h3>
<p>
Timer::Enable(false) can function as a way to pause the program.
Timer will count the time lost while disabled which affects Timer::GetElapsedTime().
The variant GetElapsedTimeReal() counts time even when Timer is disabled (paused).
Special callbacks that cannot be disabled should call the special GetElapsedTimeReal()
else their timing calculations will malfunction after pausing.
</p>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Sun Nov 22 21:22:57 CST 2009
<!-- hhmts end -->
</font>
</p>

</body>
</html>
